<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>Itcl_PreserveData manual page - [incr Tcl] Library Procedures</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">[incr Tcl] Package C API, version 4.2.1</a> <small>&gt;</small> Preserve</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<H3><A NAME="M2">NAME</A></H3>
Itcl_Alloc, Itcl_Free, Itcl_PreserveData, Itcl_ReleaseData, Itcl_EventuallyFree &mdash; Manipulate an Itcl list object.
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;itcl.h&gt;</B><BR>
<BR>
void *<BR>
<B>Itcl_Alloc</B>(<I>size</I>)<BR>
<BR>
void<BR>
<B>Itcl_PreserveData</B>(<I>ptr</I>)<BR>
<BR>
void<BR>
<B>Itcl_ReleaseData</B>(<I>ptr</I>)<BR>
<BR>
void<BR>
<B>Itcl_EventuallyFree</B>(<I>ptr, fproc</I>)<BR>
<BR>
void<BR>
<B>Itcl_Free</B>(<I>ptr</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT>size_t <B>size</B> (in)<DD>
Number of bytes to allocate.
<P><DT>void <B>*ptr</B> (in)<DD>
Pointer value allocated by <B>Itcl_Alloc</B>.
<P><DT>Tcl_FreeProc <B>*fproc</B> (in)<DD>
Address of function to call when the block is to be freed.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
These procedures are used to allocate and release memory, especially blocks
of memory that will be used by multiple independent modules. They are similar
in function to the routines in the public Tcl interface, <B><A HREF="../TclLib/Alloc.htm">Tcl_Alloc</A></B>,
<B><A HREF="../TclLib/Alloc.htm">Tcl_Free</A></B>, <B><A HREF="../TclLib/Preserve.htm">Tcl_Preserve</A></B>, <B><A HREF="../TclLib/Preserve.htm">Tcl_Release</A></B>, and
<B><A HREF="../TclLib/Preserve.htm">Tcl_EventuallyFree</A></B>. The Tcl routines suffer from issues with
performance scaling as the number of blocks managed grows large. The facilities
of Itcl encounter these performance scaling issues and require an
alternative that does not suffer from them.
<P>
<B>Itcl_Alloc</B> returns an untyped pointer to an allocated block
of memory of at least <I>size</I> bytes. All <I>size</I> bytes are
initialized to zero.
<P>
A module calls <B>Itcl_PreserveData</B> on a pointer <I>ptr</I>
allocated by <B>Itcl_Alloc</B> to prevent deallocation of that memory while
the module remains interested in it.
<P>
A module calls <B>Itcl_ReleaseData</B> on a pointer <I>ptr</I> previously
preserved by <B>Itcl_PreserveData</B> to indicate the module no longer has
an interest in the block of memory, and will not be disturbed by its
deallocation.
<P>
<B>Itcl_EventuallyFree</B> is called on a pointer <I>ptr</I> allocated by
<B>Itcl_Alloc</B> to register a deallocation routine <I>fproc</I> to be
called when the number of calls to <B>Itcl_ReleaseData</B> on <I>ptr</I>
matches the number of calls to <B>Itcl_PreserveData</B> on <I>ptr</I>. This
condition indicates all modules have ended their interest in the block
of memory and a call to <I>fproc</I> with argument <I>ptr</I> will deallocate
the memory that no module needs anymore.
<P>
<B>Itcl_Free</B> is a deallocation routine for a <I>ptr</I> value allocated
by <B>Itcl_Alloc</B>. It may be called on any <I>ptr</I> with no history of
an <B>Itcl_PreserveData</B> call unmatched by an <B>Itcl_ReleaseData</B>
call. It is best used as an <I>fproc</I> argument to <B>Itcl_EventuallyFree</B>
or as a routine called from within such an <I>fproc</I> routine. It can also
be used to deallocate a <I>ptr</I> value when it can be assured that value
has never been passed to <B>Itcl_PreserveData</B> or <B>Itcl_EventuallyFree</B>.

<H3><A NAME="M6">KEYWORDS</A></H3>
<A href="../Keywords/F.htm#free">free</A>, <A href="../Keywords/M.htm#memory">memory</A>
<div class="copy">Copyright &copy; 1993-1998 Lucent Technologies, Inc.
</div>
</BODY></HTML>
